jetcrab\vm\executor/
core.rs

1//! # VM Executor Core
2//!
3//! Provides the main executor interface that combines all VM components
4//! into a single, easy-to-use execution engine. This is the primary entry
5//! point for executing bytecode in the JetCrab VM.
6//!
7//! ## Overview
8//!
9//! The `Executor` struct integrates:
10//! - Stack management for value operations
11//! - Heap management for object allocation
12//! - Variable management for local/global variables
13//! - Instruction execution engine
14//!
15//! ## Architecture
16//!
17//! The executor uses concrete implementations of the execution traits,
18//! providing a complete VM runtime that can execute JavaScript-like
19//! bytecode with proper memory management and error handling.
20//!
21//! ## Usage
22//!
23//! ```rust
24//! use jetcrab::vm::executor::Executor;
25//! use jetcrab::vm::bytecode::Bytecode;
26//! use jetcrab::vm::value::Value;
27//!
28//! let mut executor = Executor::new();
29//! let bytecode = Bytecode::new();
30//! let constants = vec![Value::Number(42.0)];
31//!
32//! match executor.execute(&bytecode, &constants) {
33//!     Ok(()) => println!("Execution successful"),
34//!     Err(e) => eprintln!("Execution failed: {:?}", e),
35//! }
36//! ```
37
38use crate::vm::bytecode::Bytecode;
39use crate::vm::value::Value;
40use super::{
41    InstructionExecutor,
42    stack_manager::StackManager,
43    heap_manager::HeapManager,
44    variable_manager::VariableManagerImpl,
45    instruction_executor::InstructionExecutorImpl,
46};
47
48/// Main VM executor that combines all execution components
49///
50/// Provides a high-level interface for executing bytecode by integrating
51/// stack management, heap management, variable management, and instruction
52/// execution into a single, cohesive system.
53pub struct Executor {
54    instruction_executor: InstructionExecutorImpl<StackManager, HeapManager, VariableManagerImpl>,
55}
56
57impl Default for Executor {
58    fn default() -> Self {
59        Self::new()
60    }
61}
62
63impl Executor {
64    /// Creates a new executor with default components
65    ///
66    /// Initializes the executor with new instances of all required
67    /// components: stack manager, heap manager, variable manager,
68    /// and instruction executor.
69    ///
70    /// # Returns
71    /// A new executor ready for bytecode execution
72    ///
73    /// # Examples
74    ///
75    /// ```rust
76    /// use jetcrab::vm::executor::Executor;
77    ///
78    /// let mut executor = Executor::new();
79    /// ```
80    pub fn new() -> Self {
81        let stack_manager = StackManager::new();
82        let heap_manager = HeapManager::new();
83        let variable_manager = VariableManagerImpl::new();
84        
85        let instruction_executor = InstructionExecutorImpl::new(
86            stack_manager,
87            heap_manager,
88            variable_manager,
89        );
90
91        Self {
92            instruction_executor,
93        }
94    }
95
96    /// Executes bytecode with the provided constants
97    ///
98    /// Runs the complete execution cycle for the given bytecode,
99    /// using the provided constants array for constant lookups.
100    ///
101    /// # Arguments
102    /// * `bytecode` - The bytecode to execute
103    /// * `constants` - Array of constant values
104    ///
105    /// # Returns
106    /// * `Ok(())` - Execution completed successfully
107    /// * `Err(ExecutionError)` - Execution failed
108    ///
109    /// # Examples
110    ///
111    /// ```rust
112    /// let bytecode = Bytecode::new();
113    /// let constants = vec![Value::Number(42.0)];
114    /// executor.execute(&bytecode, &constants)?;
115    /// ```
116    pub fn execute(&mut self, bytecode: &Bytecode, constants: &[Value]) -> Result<(), crate::vm::executor::error_handler::ExecutionError> {
117        self.instruction_executor.execute(bytecode, constants)
118    }
119
120    /// Gets read-only access to the VM stack
121    ///
122    /// Provides access to the current state of the execution stack
123    /// for inspection and debugging purposes.
124    pub fn stack(&self) -> &crate::vm::stack::Stack {
125        self.instruction_executor.stack_manager().stack()
126    }
127
128    /// Gets mutable access to the VM stack
129    ///
130    /// Provides write access to the execution stack for direct
131    /// manipulation and testing purposes.
132    pub fn stack_mut(&mut self) -> &mut crate::vm::stack::Stack {
133        self.instruction_executor.stack_manager_mut().stack_mut()
134    }
135
136    /// Gets read-only access to the VM heap
137    ///
138    /// Provides access to the current state of the execution heap
139    /// for inspection and debugging purposes.
140    pub fn heap(&self) -> &crate::vm::heap::Heap {
141        self.instruction_executor.heap_manager().heap()
142    }
143
144    /// Gets mutable access to the VM heap
145    ///
146    /// Provides write access to the execution heap for direct
147    /// manipulation and testing purposes.
148    pub fn heap_mut(&mut self) -> &mut crate::vm::heap::Heap {
149        self.instruction_executor.heap_manager_mut().heap_mut()
150    }
151}
jetcrab\vm\executor/core.rs

jetcrab\vm\executor/
core.rs
